/**
 * *****************************************
 * Project: cone
 * File: ResourceHandlerContext.java
 * Creation Date: 9:33:01 PM
 * Creator: Ahmed Fawzy
 * *****************************************
 * Copyright © 2012 Devariance.
 */

package com.devariance.cone.handler;

import java.util.Map;
import java.util.Set;

import com.devariance.cone.handler.annotation.Handler;
import com.devariance.cone.handler.exception.InvalidResourceHandlerException;
import com.devariance.cone.handler.exception.ResourceHandlerException;
import com.devariance.cone.resource.Resource;

/**
 * The entity that is responsible for loading and managing the
 * {@link ResourceHandler} {@link Set}.
 * 
 * @author Ahmed Fawzy
 * @version 1.0
 * @see ResourceHandler
 */
public interface ResourceHandlerContext {

	/**
	 * Configures and loads the classes for the handlers and bind them according
	 * to their annotations.
	 * 
	 * @throws ResourceHandlerException
	 *             If configuration fails.
	 */
	void configure() throws ResourceHandlerException;

	/**
	 * Get {@link ResourceHandler} according the name specified.
	 * 
	 * @param resourceHandlerName
	 *            The {@link Handler} name.
	 * 
	 * @return The {@link ResourceHandler} returned.
	 * @throws InvalidResourceHandlerException
	 */
	ResourceHandler<? extends Resource> getResourceHandler(
			String resourceHandlerName) throws InvalidResourceHandlerException;

	/**
	 * Gets the {@link ResourceHandlerClassLoader} that is responsible for
	 * loading the classes of the loaded {@link ResourceHandler}.
	 * 
	 * @return The {@link ResourceHandlerClassLoader}.
	 */
	ResourceHandlerClassLoader getResourceHandlerClassLoader();

	/**
	 * Get {@link ResourceHandler} {@link Map} from the
	 * {@link ResourceHandlerContext}.
	 * 
	 * @return The {@link Map} of {@link Handler} and {@link ResourceHandler}
	 *         pairs.
	 */
	Map<Handler, ResourceHandler<? extends Resource>> getResourceHandlers();

	/**
	 * This method simply calls the release and configure methods consecutively
	 * using the last used {@link ResourceHandlerClassLoader}.
	 * 
	 * @throws ResourceHandlerException
	 *             If reconfiguration fails.
	 */
	void reconfigure() throws ResourceHandlerException;

	/**
	 * Releases the classes loaded and {@link ResourceHandler}.
	 * 
	 * @throws ResourceHandlerException
	 *             If release fails.
	 */
	void release() throws ResourceHandlerException;

	/**
	 * Sets the {@link ResourceHandlerClassLoader} that is responsible for
	 * loading the classes of the loaded {@link ResourceHandler}.
	 * 
	 * @param resourceHandlerClassLoader
	 *            The {@link ResourceHandlerClassLoader} to be set.
	 * 
	 */
	void setResourceHandlerClassLoader(
			ResourceHandlerClassLoader resourceHandlerClassLoader);
}
